Reading and writing binary images

READRAW(filename, rows, cols, bits, endian, skip) Returns the contents of a raw binary image file as a matrix. The binary file is interpreted to contain a rows by cols matrix of bits (8 or 16) per pixel packed integers, in "Little" or "Big" endian format, with skip bytes skipped in the header at the beginning of the file.

WRITERAW(filename, bits, endian) := M

Writes matrix M to raw binary integer image file filename, using either 8 or 16 bits per pixel, in "Little" or "Big" endian storage order.

Arguments:

M is an image matrix.

filename is a filename, in double quotes.

rows and cols are positive, non-zero integers.

bits 8 or 16.

endian the letter "B" or "L", in double quotes, standing for big- or little-endian data storage order. The value is irrelevant if the data is 8-bit, and is case-insensitive.

skip is an integer number of bytes.


Reading and writing color images

READRGB(filename) Returns the contents of image file filename (BMP, GIF, JPG, TGA, PBM, PGM, PPM, or TIF) as a packed RGB matrix.

WRITERGB(filename.extension) := M Writes packed RGB color matrix M to image file filename, with format determined by the file extension (BMP, PPM, or TIF). The function appears on the left-hand side of an assignment, and the image on the right.

Arguments:

filename is a filename, in double quotes. File type is expressed as .bmp, .ppm, or .tif after the file name.

M is an image matrix. Values must be real numbers between 0 and 65535.

Notes:

Data is written as 8-bit if it is in the range 0-255, or 16-bit if values are greater than 255.


Reading and writing grayscale images

READ_IMAGE(filename) Returns the contents of image file filename (BMP, GIF, JPG, TGA, PCX, PBM, PGM, PPM, or TIF) as a grayscale image matrix.

WRITEBMP(filename.extension) := M Writes grayscale image matrix M to image file filename, with format determined by the file extension (BMP, PPM, or TIF). The function appears on the left-hand side of an assignment, and the image on the right.

Arguments:

filename is a filename, in double quotes. File type is expressed as .bmp, .ppm, or .tif after the file name.

M is an image matrix. Values must be real numbers between 0 and 255.


Converting images - grayscale and color

gray_to_rgb(gray, colormap) Returns single color vector or packed grayscale matrix gray converted to a packed color matrix using color palette matrix colormap.

rgb_to_gray(RGB) Returns packed RGB color matrix RGB converted to grayscale.

Arguments:

gray, RGB are image matrices or vectors.

colormap is a 4-column matrix specifying grayscale intensity in the first column, and RGB values in the second through fourth columns, respectively. First column values must be real numbers between 0 and 255.

Alternatively, the functions described above can take three arguments, for example (R, G, B), where R, G, and B are scalars or matrices.


Converting images - RGB and HLS/HSV

Converting images or colors - RGB and HLS/HSV

rgb_to_hls(RGB) Returns single color vector or packed image matrix RGB in RGB color representation converted to HLS color representation.

rgb_to_hsv(RGB) Returns single color vector or packed image matrix RGB in RGB color representation converted to HSV color representation.

hls_to_rgb(HLS) Returns single color vector or packed image matrix HLS in HLS color representation converted to RGB color representation.

hsv_to_rgb(HSV) Returns single color vector or packed image matrix HSV in HSV color representation converted to RGB color representation.

Arguments:

RGB, HLS, HSV are 3 x 1 vectors (of scalars or matrices) or packed image matrices with real values between 0 and 255.

Alternatively, the functions described above can take three arguments, for example (R,G,B), where R, G, and B are scalars or matrices.


Converting between RGB and television images

rgb_to_yiq(RGB) Returns single color vector or packed image matrix RGB in RGB color representation converted to YIQ color representation.

rgb_to_ycbcr(RGB) Returns single color vector or packed image matrix RGB in RGB color representation converted to YCbCr color representation.

yiq_to_rgb(YIQ) Returns single color vector or packed image matrix YIQ in YIQ color representation converted to RGB color representation.

ycbcr_to_rgb(YCbCr) Returns single color vector or packed image matrix YCbCr in YCbCr color representation converted to RGB color representation.

Arguments:

RGB, YIQ, YCbCr are 3 x 1 vectors or packed image matrices with real values between 0 and 255.

Alternatively, the functions described above can take three arguments, for example (R,G,B), where R, G, and B are scalars or matrices.


Working with matrices

augment3(X, Y, Z) Returns a matrix formed by putting matrices (or vectors) X, Y, and Z side by side. They must all have the same number of rows.

subcolor(M, ir, jr, ic, jc) Returns the submatrix from row ir to jr, column ic to jc, of packed color matrix M.

Arguments:

M is a packed color matrix.

X, Y, Z are matrices or vectors with the same number of rows.

ir, jr, ic, jc are non-negative integers that do not exceed the number of rows or columns in the matrix M. 0 is allowed as a value only when it is allowed as the ORIGIN for arrays (see Math/Options menu).


Packed

Working with packed matrices

extract(M, n) Returns the nth color component of packed 3-color matrix M.

replace(M, N, n) Returns packed image matrix M with the nth color component replaced by matrix N, which must have the same number of rows as M and 1/3 as many columns.

Arguments:

M is a packed-color matrix.

N is one color value in a packed-color image matrix.

n is 1, 2 or 3 (optional for extract when M is a vector of three matrices)


Noise

addnoise(M, p, n) Returns matrix M with added noise, with probabilty p/2 to add or subtract n to or from the pixel intensity.

Arguments:

M is an image matrix.

p is a real number between 0 and 1, inclusive.

n is a real number with absolute value between 0 and 255, inclusive.

Notes:

The function will clip the resulting pixel values to the range 0 to 255.


Binarization

binarize(M, thresh) Returns a binarized version of matrix M with pixels above threshold thresh set to 1 and below to 0.

binarize2(M, lowThresh, highThresh, inValue, outValue) Returns a binarized version of matrix M with pixels between lowThresh and highThresh set to inValue, and pixels outside to outValue.

binarize_auto(M) Returns a binarized version of matrix M, choosing the threshold automatically.

Arguments:

M is an image matrix.

thresh is a real number.

lowThresh and highThresh are real numbers. lowThresh must be less than highThresh.

inValue and outValueare real numbers.


Quantization

imquant(M, n) Returns a quantized version of matrix M containing n equally-spaced grayscale levels between 0 and 255.

imquant2(M, v) Returns a quantized version of matrix M containing the grayscale levels in vector v.

Arguments:

M is an image matrix.

n is an integer between 2 and 256.

v is a vector of real numbers between 0 and 255, in ascending order.


Equalizing

equalize(M) Returns matrix M with grayscale pixel intensities adjusted to form a linear cumulative histogram.

Arguments:

M is an image matrix.


Mapping

funmap(M, f) Returns matrix M with function f applied to each element.

levelmap(M, vec) Returns matrix with intensity values specified by the vector vec by mapping pixel intensities in matrix M to vec's indices.

Arguments:

M is an image matrix.

f is a function in one variable.

vec is a vector of real numbers between 0 and 255, inclusive.The last index of vec must equal the highest intensity in M.


Histograms

imhist(M, n) Returns an n-bin histogram of M for values between 0 and 255 (ignores values outside that range).

imhist2(M, n) Returns an n-bin histogram of M over its range of values.

hist2d(M, N, n) Returns a two-dimensional histogram with n bins on equal-sized matrices M and N.

Arguments:

M, N are image matrices of the same size.

n is a positive integer.


Scaling and clipping

scale(M, Min, Max) Returns matrix M with elements scaled between Min and Max.

clip(M, Min, Max) Returns matrix M with elements clipped between Min and Max.

Arguments:

M is an image matrix.

Min, Max real numbers between 0 and 255.


Thresholding

threshold(M, thresh) Returns the matrix M with every element below thresh set to thresh. If thresh is negative, every element above -thresh is set to -thresh.

Arguments:

M is an image matrix.

thresh a real number.


Inverting

invert(M) Returns the matrix M with each element set to 255 minus its original value.

invert2(M) Returns the matrix M with each element set to max(M) minus its original value plus min(M).

Arguments:

M is an image matrix.


Replacing part of an image

putregion(M, N, row, col) Returns the matrix N inserted into matrix M at row row and column col.

Arguments:

M, N are image matrices.

row, col are positive integers, such that row + rows(N) - 1 < rows(M), and col + cols(N) - 1 < cols(M), .


Blending and masking

blend(M, N) Returns a blend of same-size matrices M and N (pixelwise sum - [product/255]).

mask(M, N) Returns matrix M masked by same-size matrix N - set to zero where N is zero, otherwise remains the same.

Arguments:

M, N are matrices of the same size.


Boolean functions

and(M, N) Returns the boolean AND of the two image matrices M and N, which must be the same size.

or(M,N) Returns boolean OR of the two image matrices M and N, which must be the same size.

Arguments:

M, N are image matrices.


Error measurement

relerror(M, Q) Returns the relative error between matrices M and Q.

immse(M, Q) Returns the mean-squared-error (MSE) between image matrices M and Q.

Arguments:

M, Q are image matrices.


Noise measurement

imsnr(M, Q) Returns the signal-to-noise ratio (SNR) between image matrices M and Q.

Arguments:

M, Q are image matrices of the same size.


Flipping

horzflip(M) Returns the matrix M flipped horizontally.

vertflip(M) Returns the matrix M flipped vertically.

Arguments:

M is an image matrix.


Rotating

rotate(M, angle) Returns the matrix M rotated angle degrees counterclockwise. The boundary area is set to black.

rotate90(M) Returns the matrix M rotated 90 degrees counterclockwise.

rotate180(M) Returns the matrix M rotated 180 degrees counterclockwise.

rotate270(M) Returns the matrix M rotated 270 degrees counterclockwise.

Arguments:

M is an image matrix.

angle is a real number in units of degrees.


Translating

translate(M, rows, cols, pad) Returns a matrix the same size as M, with the original elements translated by rows rows and cols columns, padding unfilled matrix elements with pad.

Arguments:

M is an image matrix.

rows, cols are integers, where the sign indicates the direction of the shift.

pad is a real number between 0 and 255, inclusive.


Warping

warp(M, T) Performs bilinear warping on matrix M, using tie-points stored in matrix T.

Arguments:

M is an image matrix.

T is an 8x2 matrix containing four pairs of tie points.


Zooming

zoom(M, hscale, vscale) Returns matrix M resized by factor hscale horizontally and vscale vertically.

Arguments:

M is an image matrix.

hscale, vscale are positive, nonzero real numbers.

Notes:

It is suggested that you not use excessively large values for hscale or vscale, because of unreasonable computation times and display problems.


Convolution

convolve3(M, K) Returns the quick convolution of matrix M with 3x3 kernel K.

convolve5(M, K) Returns the quick convolution of matrix M with 5x5 kernel K.

convol2d(M, K) Returns the convolution of matrix M with kernel K.

Arguments:

M is an image matrix.

K is a kernel matrix of a size appropriate to the function called. Elements are real numbers.


Crisping

diacrisp(M) Returns matrix M crisped with a 3x3 diagonally weighted kernel.

orthocrisp(M) Returns matrix M crisped with a 3x3 orthogonally weighted kernel.

orthocrisp5(M) Returns matrix M crisped with a 5x5 orthogonally weighted kernel.

unicrisp(M) Returns matrix M crisped with a 3x3 uniformly weighted kernel.

Arguments:

M is an image matrix.


2D image correlation

correl2d(M, K) Returns the correlation of matrix M with kernel K.

Arguments:

M is an image matrix.

K is a kernel matrix of arbitrary dimension with real elements. It should be smaller than M.


Median filtering

medfilt(M) Returns a median-filtered matrix M.

getnoise(M) Returns the difference between matrix M and median-filtered M.

Arguments:

M is an image matrix.


Quantile filtering

quantfilt(M, elem, quantile) Performs quantile filtering on M using neighborhood matrix elem and quantile probability quantile.

Arguments:

M is an image matrix.

elem is filtering kernel of arbitrary size with real elements.

quantile is a real number between zero and one, inclusive.


Smoothing

centsmooth(M) Returns matrix M smoothed with a 3x3 center weighted kernel.

unismooth(M) Returns matrix M smoothed with a 3x3 uniformly weighted kernel.

unismooth5(M) Returns matrix M smoothed with a 5x5 uniformly weighted kernel.

orthosmooth(M) Returns matrix M smoothed with a 3x3 orthogonally weighted kernel.

orthosmooth5(M) Returns matrix M smoothed with a 5x5 orthogonally weighted kernel.

Arguments:

M is an image matrix.


Wiener filtering

wiener2d(M, win_h, win_w) Performs 2-D adaptive Wiener filtering on M using a local window win_w pixels wide by win_h pixels high.

Arguments:

M is an image matrix.

win_h, win_w are integers.


Erosion

erode(M, Melem, r_origin, c_origin, b) Performs binary erosion on matrix M at threshold b using structuring element Melem with origin at row r_origin and column c_origin.

erode4(M, b) Performs erosion on matrix M at threshold b using 4 neighbors.

erode8(M, b) Performs erosion on matrix M at threshold b using 4 neighbors.

Arguments:

M is an image matrix.

Melem is a vector or matrix.

b is a real number.

r_origin, c_origin are integers, where sign indicates direction.

Notes:

The erode function has binary output: foreground is always set to 255, while background is always set to 0.


Dilation

dilate(M, Melem, r_origin, c_origin, b) Performs binary dilation on matrix M at threshold b using structuring element Melem with origin at row r_origin and column c_origin.

dilate4(M, b) Performs dilation on matrix M at threshold b using 4 neighbors.

dilate8(M, b) Performs dilation on matrix M at threshold b using 4 neighbors.

Arguments:

M is an image matrix.

Melem is a vector or matrix.

b is a real number.

r_origin, c_origin are integers, where sign indicates direction.

Notes:

The dilate function has binary output: foreground is always set to 255, while background is always set to 0.


Opening and closing

open(M, Melem, b) Performs binary opening on matrix M at threshold b using structuring element Melem.

close(M, Melem, b) Performs binary closing on matrix M at threshold b using structuring element Melem.

Arguments:

M is an image matrix.

Melem is a vector or matrix.

b is a real number.

Notes:

These functions have binary output: foreground is always set to 255, while background is always set to 0.


Gray scale morphology

gray_erode(M, Melem, r_origin, c_origin ) Performs grayscale erosion on matrix M using structuring element Melem with origin at row r_origin and column c_origin.

gray_open(M, Melem) Performs grayscale opening on matrix M with structuring element Melem.

gray_dilate(M, Melem, r_origin, c_origin ) Performs grayscale dilation on matrix M using structuring element Melem with origin at row r_origin and column c_origin.

gray_close(M, Melem) Performs grayscale closeing on matrix M with structuring element Melem.

Arguments:

M is an image matrix.

Melem is a vector or matrix.

r_origin, c_origin are integers, where sign indicates direction.


Thinning and skeletonizing

thin(M, b) Returns the thinned version of matrix M binarized with threshold b.

skeleton(B) Returns binary matrix B eroded to its innermost level.

skeleton2(M, b) Returns the skeleton of matrix M binarized with threshold b.

Arguments:

M is an image matrix.

B is a binarized image matrix.

b is a real number.


Filtering in the Fourier transform domain

funconv(M, f) Convolution of matrix M with frequency domain function f.

funcdeconv(M, f, e) Deconvolution of matrix M with frequency domain function f and error e.

matconv(M, N) Convolution of matrix M with frequency domain mask N.

matdeconv(M, N, e) Deconvolution of matrix M with frequency domain mask N and error e.

Arguments:

M is an image matrix in the spatial or frequency domain.

N is matrix of real numbers.

f is a real-valued function in one variable.

e is a positive real number.


Filtering with a Gaussian kernel

gaussconv(M, s) Convolution of matrix M with frequency domain gaussian of half-width s.

gaussdeconv(M, s, e) Deconvolution of matrix M with frequency domain gaussian of half-width s with error e.

Arguments:

M is an image matrix in the spatial or frequency domain.


Recentering an image

center(M) Returns fourier transform of the matrix M so that the DC component is in the center.

Arguments:

M is an image matrix.


Wavelet transform filtering

iwave2d(M, n) Returns the n-level inverse wavelet transform of M.

wave2d(M, n) Returns the n-level wavelet tranform of M.

wavescale(M, n, Min, Max) The n-level wavelet transform of M, scaled between Min and Max.

Arguments:

M is an image matrix.

n is a positive integer, or 0.

Min, Max are real numbers.


Discrete cosine transform

dct2d(M) Returns the 2D discrete cosine transform (type II) of matrix M.

idct2d(M) Returns the inverse 2D discrete cosine transform (type II) of matrix M.

Arguments:

M is an image matrix.


Canny edge finder

canny(M, sigma, low, high) Returns a binary edge image resulting from Canny edge detection on matrix M, using standard deviation sigma and hysteresis thresholds low and high.

Arguments:

M is an image matrix.

sigma is a real number greater than zero, typically between 0 and 2.

low, high are real numbers and low < high.


Convolution edge finders

difedge(M) Performs edge-detection by differential convolution on matrix M.

freichen(M) Performs edge detection by Frei-Chen convolution on matrix M.

prewitt(M) Performs edge detection by Prewitt convolution on matrix M.

roberts(M) Performs edge detection by Roberts convolution on matrix M.

sobel(M) Performs edge detection by Sobel convolution on matrix M.

Arguments:

M is an image matrix.


Convolution and comparison edge finders

compgrad(M) Performs edge detection by comparing the gradients of the 8 neighbors on matrix M.

kirsch(M) Performs edge detection by kirsch convolution and comparison on matrix M.

robinson3(M) Performs edge detection by 3x3 Robinson convolution and comparison on matrix M.

robinson5(M) Performs edge detection by 5x5 Robinson convolution and comparison on matrix M.

Arguments:

M is an image matrix.


Laplacian edge finders

laplace4(M) Returns the convolution of matrix M with a 3x3 Laplacian kernel. The kernel's center is 4.

laplace8(M) Returns the convolution of matrix M with a 3x3 Laplacian kernel. The kernel's center is 8.

laplace24(M) Returns the convolution of matrix M with a 5x5 Laplacian kernel. The kernel's center is 24.

Arguments:

M is an image matrix.


Gradients

rowgrad(M) Returns the row gradient (difference by rows) of matrix M.

colgrad(M) Returns the column gradient (difference by columns) of matrix M.

Arguments:

M is an image matrix.


Connected component labeling

concomp(M, con, fg) Performs connected component labeling of the pixels with grayscale value fg in matrix M, considering 4-connected neighbors if con is 4 or 8-connected if con is 8.

Arguments:

M is an image matrix.

con is either 4 or 8.

fg is a real number.


Convex hull

cnvxhull(M, fg) Returns a matrix containing the convex hull of pixels of value fg in matrix M.

Arguments:

M is an image matrix.

fg is a real number appearing in at least one element in M.


Euclidean distance transform

distform(M, fg) Returns the distance transform of image M using foreground gray value fg.

Arguments:

M is an image matrix.

fg is a real number.


Moment Invariants

moment_invariant(M) Returns a vector containing the seven typical moment invariants of M.

Arguments:

M is an image matrix.


Shape features

shape_features(M) Returns a matrix of moments and shape features for each distinct pixel value in labeled image M.

Arguments:

M is an image matrix.


Region growing

reg_grow(M,x_gridsize,y_gridsize,num_regions) Performs the piecewise-constant energy-based region growing segmentation of M into num_regions regions, using initial grid spaced by x_gridsize along x and y_gridsize along y.

Arguments:

M is an image matrix.

x_gridsize, y_gridsize are integers greater than or equal to 2, and divisors of the image size.

num_regions is an integer greater than or equal to 2.


Welcome

The Help window for this Extension Pack has three tabs for accessing information:

  • The Contents tab gives you access to a Table of Contents which is useful when you need an overview of topics available and a guide through them.

  • The Index tab directs you to specific topics you request. Use the Index if you know the topic you are looking for.

  • The Search tab searches the entire help system for a word or phrase you request. Full-text searching is useful when you are looking for a certain word or phrase, rather than a topic.

When you double-click on a topic, it displays in the right-hand side of the window.